
# Necklace\XxHash - PHP FFI bindings for libxxhash

This is an FFI binding of the `libxxHash` library from [xxHash](https://github.com/Cyan4973/xxHash) for PHP.

You're here because:

- You want [xxHash](https://github.com/Cyan4973/xxHash) in PHP.
- You don't want to install an extension.
- You're fine with installing the `xxhash` package on your system to get libxxHash.
- You want speed, or at least more speed than a pure PHP implementation of xxHash could get.

If so, you're in the right place.

## Getting started

### Setup

You will obviously need the `xxHash` package.
In addition you will need `libffi`, and enable FFI for PHP (You will therefore need PHP version 7.4 or above).
libxxhash needs to be v0.6.4 or above.

Here are some common ways to install:

- Arch GNU/Linux: `sudo pacman -S xxhash libffi`
- Debian / Ubundu: `sudo apt install xxhash libffi`
- Fedora: `sudo dnf install xxhash libffi`
- OpenSUSE: `sudo zypper install xxhash libffi`

PHP has to be compiled with the `--with-ffi` option, most distributions will have done this.

Locate the relevant `php.ini` file on your system and make sure these two lines are present, uncommented:

```
extension=ffi
ffi.enable=true
```

Then, simply add the bindings to your project:

```
composer require necklace/xxhash-ffi
```

### Let me hash already!

Alright, alright. I know what you want, and I got what you need. You've got files, we got hashes:

#### Hash a file

```
<?php

use Necklace\XxHash\XxHash64;

$xxh = new XxHash64;

echo $xxh->hashFile('filename');
```

> cee0f97cde3a4cda

#### Hey man, I want the latest, fastest, and greatest!

This library supports the [XXH3](https://fastcompression.blogspot.com/2019/03/presenting-xxh3.html) algorithm, 
you can use this but beware; it's still labeled experimental : return values from this version are not comparable with other versions.

```
<?php

use Necklace\XxHash\Xxh3\XxHash64;

$xxh = new XxHash64;

echo $xxh->hashFile('filename');
```

> db70939c6397e562

Look in `tests/` for more examples.

## License

This repository and all its files is under the same license as the [xxHash](https://github.com/Cyan4973/xxHash) project; the [BSD 2-Clause License](https://choosealicense.com/licenses/bsd-2-clause/).

See COPYING or LICENSE.txt.

## Development

Clone and run `composer install`.

Remember to run `~/.config/composer/vendor/bin/php-cs-fixer fix src/`

### Tests

Run all tests with `php vendor/bin/phpunit` from the top directory.

Test memory leaks in tests with `vendor/bin/roave-no-leaks`.